@aller/cyclops-frontend-api

cyclops-frontend-api

API-part of the cyclops-frontend. This package contains all non-DOM changes, and interactions with CYCLOPS, from login, to payment-initiations, to user-fetching and whatnot. Below are more content and info on functions, schemas, interfaces that are being used in this package..

This package utilizes Ajv for response-validation from data fetched from cyclops. Most of the functions that has validation, also has a counterpart of unvalidated output, for situations where testing is necessary, or the data sent back is not needed for anything.

When fetching a user through /users/me a cyclops_seg cookie is set, if the user has adSegments as a property.

Please note that this library is still in active development..

Table of Contents

• Design
• Using the package
• Functions
  • User
    • GET
  • Subscription
    • DELETE
  • Payment
    • POST
  • Cyclops
    • GET
    • POST
    • DELETE
    • Login/Logout
  • Catalogue
    • GET
• Constants
  • Cyclops
• Schemas
  • User
  • Subscription
  • Newsletter
  • Product
  • Payment
  • Catalogue
  • Brand
• Interfaces
  • User
  • Subscription
  • Newsletter
  • Product
  • Payment
  • Catalogue
  • Brand

Design

Interfaces can be found in ./src/**/interface.ts, the same with schemas (./src/**/schema.ts) and validators (./src/**/validator.ts).

Using the package

If you are not afraid of bloat, this package can be used with @aller/cyclops-frontend-api. If you are afraid of bloat, everything can be referenced with @aller/cyclops-frontend-api/lib/** (e.g. @aller/cyclops-frontend-api/lib/user/login). In this, you'll only include the parts of code you actually need, instead of the whole package.

Functions

User

GET

/**
 * Get the current (possibly-cached) user based on
 * the cyclops-session cookie
 * Use this function if you want to check if a user is logged.
 */

async getCurrentUser(
    domain: string = '',
    options?: any
): Promise<IUser>

/**
 * Get the current (possibly-cached) user based on
 * the cyclops-session cookie, but without any validation
 * Use this function if you want to check if a user is logged.
 */

async getCurrentUserUnvalidated(
    domain: string = '',
    options?: any
): Promise<any>

/**
 * Get the current non-cached user based on the
 * cyclops-session cookie
 * This function has a performance cost and should only be used
 * if the exact state of the user is required (minside)
 */

async getCannonicalUser(
    domain: string = '',
    options?: any
): Promise<IUser>

/**
 * Get the current non-cached user based on
 * the cyclops-session cookie
 * This function has a performance cost and should only be used
 * if the exact state of the user is required (minside)
 */

async getCannonicalUserUnvalidated(
  domain: string = '',
  options?: any
): Promise<any>

Subscription

DELETE

/**
 * Get the current (possibly-cached) user
 * based on the cyclops-session cookie
 * Use this function if you want to check if a user is logged.
 */

async unsubscribe(
  productId: string,
  domain: string = '',
  options?: any
): Promise<boolean>

Payment

POST

/**
 * Initiates a payment for a product, and deal
 */

async initiatePayment(
  productId: string,
  dealId: string,
  options: IPaymentOptions = defaultPaymentOptions,
  domain: string = '',
  fetchOptions?: any
): Promise<IPaymentInitResponse>

Cyclops

GET

/**
 * Gets from cyclops, and inputs a validator
 * and interface to validate the output
 */

async cyclopsGet<T>(
  path: string,
  converter: (json: unknown) => T,
  domain: string = '',
  options?: any
): Promise<T>

/**
 * Gets from cyclops, without validation
 */

async cyclopsGetUnvalidated(
  path: string,
  domain: string = '',
  options?: any
): Promise<any>

POST

DELETE

Login/Logut

/**
 * Initiates a cyclops login redirect. Redirect parameter
 * says whether to add a redirect url
 */

cyclopsLogin(
    redirect?: string,
    domain: string = '',
    options?: any
)

/**
 * Initiates a cyclops logout
 */

async cyclopsLogout(
    refresh: boolean = false,
    domain: string = '',
    options?: any
)

Catalogue

GET

/**
 * Gets catalogue and validates the response
 * to be valid ICatalogue
 */

async getCatalogue(
  domain: string = '',
  options?: any
): Promise<ICatalogue>

/**
 * Gets catalogue without validation
 */

getCatalogueUnvalidated = async (
  domain: string = '',
  options?: any
): Promise<ICatalogue>

Constants

Cyclops

/**
 * Creates relative loginURL
 */

export const cyclopsLoginRelativeURL = (
  redirect?: string,
  domain: string = '',
  options?: any,
): string => {
  const red = redirect ? redirect : window.location.pathname;
  const relativeUrl = `${domain}${CYCLOPS_API}/login?cyclops-redirect=${red}`;
  return relativeUrl;
};

/**
 * Creates relative loginURL without utilizing any window
 * or document elements
 */

export const cyclopsLoginRelativeURLServer = (
  redirect?: string,
  domain: string = '',
  options?: any,
): string => {
  const red = redirect ? `?cyclops-redirect=${redirect}` : '';
  const relativeUrl = `${domain}${CYCLOPS_API}/${red}`;
  return relativeUrl;
};

Schemas

User

export const userSchema = {
  $id: 'https://www.aller.no/schemas/user.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'IUser',
  type: 'object',
  properties: {
    cyclopsId: { type: 'string' },
    mediaConnectId: { type: 'string' },
    aid: { type: 'string' },
    email: { type: 'string' },
    fullName: { type: 'string' },
    phoneNumber: { type: 'string' },
    subscriptions: {
      type: ['array'],
      items: { $ref: 'https://www.aller.no/schemas/subscription.json' },
    },
    newsletters: {
      type: ['array'],
      items: { $ref: 'https://www.aller.no/schemas/newsletter.json' },
    },
  },
  required: [
    'cyclopsId',
    'mediaConnectId',
    'aid',
    'email',
    'fullName',
    'phoneNumber',
  ],
};

Subscription

subscriptionSchema = {
  $id: 'https://www.aller.no/schemas/subscription.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'ISubscription',
  type: 'object',
  properties: {
    status: { type: 'string', enum: ['ACTIVE', 'CANCELLED'] },
    productId: { type: 'string' },
    endDate: { type: 'string' },
  },
  required: ['status', 'productId'],
};

Newsletter

newsletterSchema = {
  $id: 'https://www.aller.no/schemas/newsletter.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'INewsletter',
  type: 'object',
  properties: {
    newsletterId: { type: 'string' },
    site: { type: 'string' },
  },
  required: ['newsletterId', 'site'],
};

Product

productSchema = {
  $id: 'https://www.aller.no/schemas/product.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'IProduct',
  type: 'object',

  properties: {
    productName: { type: 'string' },
    productDescription: { type: 'string' },
    productId: { type: 'string' },
    productLogo: { type: 'string' },
    productType: { type: 'string', enum: ['digital', 'print'] },
    deals: {
      type: 'array',
      items: { $ref: 'https://www.aller.no/schemas/productDeal.json' },
    },
  },
  required: [
    'productName',
    'productDescription',
    'productId',
    'productLogo',
    'productType',
    'deals',
  ],
};

productDealSchema = {
  $id: 'https://www.aller.no/schemas/productDeal.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'IProductDeal',
  type: 'object',
  properties: {
    dealName: { type: 'string' },
    dealDescription: { type: 'string' },
    dealId: { type: 'string' },
    dealLogo: { type: 'string' },
    fullTermsDescription: { type: 'string' },
  },
  required: [
    'dealName',
    'dealDescription',
    'dealId',
    'dealLogo',
    'fullTermsDescription',
  ],
};

Payment

paymenInitResponseSchema = {
  $id: 'https://www.aller.no/schemas/paymenInitResponse.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'IUser',
  type: 'object',
  properties: {
    paymentId: { type: 'string' },
    paymentProvider: { type: 'string' },
    reservationId: { type: 'string' },
  },
  required: ['paymentId', 'paymentProvider'],
};

Catalogue

catalogueSchema = {
  $id: 'https://www.aller.no/schemas/catalogue.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'ICatalogue',
  type: 'object',
  properties: {
    brands: {
      type: 'array',
      items: { $ref: 'https://www.aller.no/schemas/brand.json' },
    },
  },
  required: ['brands'],
};

Brand

brandSchema = {
  $id: 'https://www.aller.no/schemas/brand.json',
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'IBrand',
  type: 'object',
  properties: {
    brandName: { type: 'string' },
    brandDescription: { type: 'string' },
    brandId: { type: 'string' },
    brandLogo: { type: 'string' },
    products: {
      type: 'array',
      items: { $ref: 'https://www.aller.no/schemas/product.json' },
    },
  },
  required: [
    'brandName',
    'brandDescription',
    'brandId',
    'brandLogo',
    'products',
  ],
};

Interfaces

User

interface IUser {
  readonly cyclopsId: string;
  readonly mediaConnectId: string;
  readonly aid: string;
  readonly email: string;
  readonly fullName: string;
  readonly phoneNumber: string;
  readonly subscriptions?: ReadonlyArray<ISubscription>;
  readonly newsletters?: ReadonlyArray<INewsletter>;
}

Subscription

interface ISubscription {
  readonly status: 'ACTIVE' | 'CANCELLED';
  readonly productId: string;
  readonly endDate?: string;
}

Newsletter

interface INewsletter {
  readonly newsletterId: string;
  readonly site: string;
}

Product

interface IProduct {
  readonly productName: string;
  readonly productDescription: string;
  readonly productId: string;
  readonly productLogo: string;
  readonly productType: 'digital' | 'print';
  readonly deals: ReadonlyArray<IProductDeal>;
}

interface IProductDeal {
  readonly dealName: string;
  readonly dealDescription: string;
  readonly dealId: string;
  readonly dealLogo: string;
  readonly fullTermsDescription: string;
}

Payment

interface IPaymentInitRequest {
  productId: string;
  dealId: string;
  embeddedCheckoutUrl: string;
  allowUnauthenticatedCheckout: boolean;
}

interface IPaymentInitResponse {
  paymentId: string;
  paymentProvider: string;
  reservationId?: string;
}

interface IPaymentOptions {
  allowUnauthenticatedCheckout?: boolean;
  embeddedCheckoutUrl?: string;
}

Catalogue

interface ICatalogue {
  readonly brands: ReadonlyArray<IBrand>;
}

Brand

interface IBrand {
  readonly brandName: string;
  readonly brandDescription: string;
  readonly brandId: string;
  readonly brandLogo: string;
  readonly products: ReadonlyArray<IProduct>;
}